QRZ! Ham Radio 6/QRZ Ham Radio Callsign Database - Volume 6.iso/pc/files/p_msys/msys116.exe/HAPNMSYS.COM/HAPN-API.DOC

Text File | 1991-01-14 | 14.0 KB | 442 lines

HAPN1.SYS DEVICE DRIVER



(C) Copyright Hamilton and Area Packet Network 1990



DESCRIPTION


HAPN1.SYS is a  device driver that  supports the  8273 HDLC controller on the
HAPN-1 adapter. In order to use it, it must be defined in the DOS  CONFIG.SYS
file. DOS will then load it when the system is booted.

The  CONFIG.SYS entry appears as follows, where  items within square  brakets
are optional:

device=[d:\path\]hapn1.sys [base=bbb][,irq=i][,cts=xx][,ttsiz=z]
                           [,rxbuffers=rr][,txbuffers=tt]
                           [,reserve=y/n][,pri=n][,tim=alt]

where bbb is the adapter 8273 base address (in hex) (i.e. 310).
          The default value is 310.
        i is the IRQ level. Values may be 0 through 7, and the
          default value is 2.
       rr is the number of Rx buffers to allocate. Minimum
          number is 10, maximum number is 99, default number is 25.
       tt is the number of Tx buffers to allocate. Minimum
          number is 10, maximum number is 99, default number is 15.
       xx is the clear-to-send delay in timer ticks (55 ms).
          Values are 0 to 99, with default value 0.
        z is the size of the trace table in kbytes. May be between
          1 and 9. The default value is 4. Set it smaller to conserve
          memory and larger to do datastream debugging.
    pri=n (priority=no) By default the driver will change the priority
          on the PC's interrupt controller so that the adapter interrupt
          has the highest priority. This parameter tells the driver to
          leave the interrupt controller priority setting alone. Use
          this parameter when you have more than one adapter installed,
          to help you manage the interrupt priorities. If the adapter
          interrupt priority is not high enough, you will get numerous
          interrupt overruns and underruns.
  tim=alt tells the driver to use int 1c (hex) for the timer tick
          interrupt instead of int 8. Int 8 is generally more reliable
          when programs are run that use the timer tick interrupt but
          do not share it properly; however in some cases it may be
          desired to use int 1c instead.

The  device  driver contains all  the HAPN-1 adapter hardware  specific  code
(level 1). It is used by M25.COM, which provides the AX.25 support (level 2).










HAPN1.SYS Device Driver                                                     1


PROGRAMMING INTERFACE


Although  the driver may be opened as a DOS file,  it  does  not provide  I/O
services via  DOS. This  is because DOS is not re-entrant, and  M25  must get
access to the HAPN-1 driver from the timer tick  interrupt. If the timer tick
interrupt  occurs while  an application program  is  accessing  DOS  for some
function, and M25 tried to access HAPN1.SYS via DOS,  the system would crash.
Therefore, an alternate means is  provided for programs such as M25 to access
the functions within HAPN1.SYS without using DOS.

Programs wishing to access HAPN1.SYS directly may do so as follows:

1.  Issue DOS OPEN to file with name  "HAPN1-A1" for adapter 1 and "HAPN1-A2"
    for adapter 2.

2.  Using  the handle returned from the open, issue  a  DOS IOCTL  READ for 4
    bytes  of data. The 4 bytes are the long address of the HAPN1.SYS program
    interface.

3.  Issue DOS CLOSE.

The interface is then  accessed by  loading  a request  code in ah  register,
possibly loading other registers,  and issuing a far call to the api address.
From assembler this  is simply done by a call  instruction.  Other  languages
must  provide a means to  load  registers  (including segment  registers) and
issue  a far call.  (CI C/86 provides a  function  called farcall  which does
this.)

The api function code goes  in ah for every call.  For most calls, a  port id
goes in al. Port ids are  integers starting with  0.  Use  the "Get number of
ports..." api function call to find out how  many ports  are supported by the
driver. If you  use an invalid port id, calls to the  api will do nothing and
return error if possible. (Note: the HAPN-1  supports only one port,  port 0.
However multi-ported adapters may be available in the future.)



Activate Driver


Load  ah  with 0  and call the api.  The  driver will be  activated and start
receiving  packets. If  the  driver is  already active, the  8273  port B  is
updated. There is no return code.



De-activate Driver


Load ah with 1 and call the  api. The  driver will be  de-activated.  If  the
driver is already inactive, -1 is returned in AX, otherwise 0 is returned.









HAPN1.SYS Device Driver                                                     2


Read a Frame


Load ah with 2, load es:di  with the address of  a  buffer,  load cx with the
size of the  buffer,  and load al with the port number.  Call  the api.  If a
frame  is available, it will be  moved to your buffer and the number of bytes
returned in ax. If no frame is available,  ax will be returned with 0. If the
frame is  larger than your buffer, only the amount requested will be returned
and the rest discarded.  Use  the  "get maximum frame  size"  api function to
find out the size of the HAPN-1 internal buffer.



Write a Frame


Load ah with 3,  load es:di with the  address of the buffer, load cx with the
length  of  data  in the buffer, and  load  al with  the port  number.  If  a
transmit buffer is available, your frame will be copied in and the  number of
bytes  returned in ax. If no  transmit  buffers  are  available,  ax will  be
returned with 0. If your data is longer than the size of the transmit buffer,
only the transmit buffer  length will be copied and transmitted, and the rest
discarded.  In  this  case ax  will  contain  the  number of  bytes  actually
accepted. Use the "get maximum frame size" api function  to find out the size
of the HAPN-1 internal buffer.



Request Transmission


Load ah with 4, and load al with the port number.  Call the  api.  Any frames
in the Tx buffers will be transmitted. The RTS signal  will be  asserted, and
the frames  transmitted after the clear-to-send delay number  of  timer ticks
have  elapsed. (The CTS delay defaults to  0 or whatever was on the HAPN1.SYS
command  line, and  may  be changed  using the "set  Clear-To-Send delay" api
function.)  The driver does not test for carrier  detect before transmitting.
It is the user's responsibility to do this and issue this api function at the
appropriate time. If  necessary,  use  the  "get carrier  detect  state"  api
function to test the channel.



Get Driver Status


Load ah with 5 and call the api. On  return,  ax  will be 0 if  the driver is
inactive, and 1 if the driver is active.



Get Trace Table Data


Load ah  with 6,  load es:di with the  address of a  buffer, load cx with the
size of the buffer,  and load  al with  the port  number.  Call  the api. The
trace table will be returned in your buffer, up to the size passed in cx. The
buffer  should  be  large  enough  for  the  whole  trace table, since  it is
wrap-around. The size may be obtained  from  the  "get  trace table size" api


HAPN1.SYS Device Driver                                                     3


function,  described below.  The  trace table includes  a 4-byte  header. The
header  consists of 2 words, the first being the size of the data area of the
trace table, and the second being the offset to the  next  byte to use in the
data area.



Get Statistical Counters


Load ah with 7, load es:di with the address of a buffer, and load cx with the
size of the  buffer,  and load al with  the port  number.  Call the  api. The
statistical counters  will be returned in your buffer, up to the size  passed
in cx. The statistical counters are all long (4 bytes), and the buffer should
be 100 bytes (i.3. 25 counters).



Get Carrier Detect State


Load ah with 8, and  load  al with the port number.  Call the api. On return,
ax will be 0 if there is no carrier detect, 1 if there is carrier detect, and
-1 if the status cannot be determined.  Indeterminant  carrier  detect occurs
when the driver is transmitting and  cannot  test the channel. In this  case,
the application should interpret the channel as busy.



Set 8273 Port B


Load ah with 9, put the port B state in cl, and load al with the port number.
Call  the api.  For the  change  to become  effective, the adapter  should be
activated  after changing port B.  (Activating the driver when it is  already
active is OK and will do nothing except reset port B.)



Get Trace Table Size


Load ah with 10 and load al with  the port number.  Call the  api. On return,
ax will contain the trace table size, including the header.



Set Clear-To-Send Delay


Load  ah with 11, put the CTS delay in cx, and  load al with the port number.
Call the api. The CTS delay is measured in timer ticks, where one tick equals
55  milliseconds.  Note that the default  value is  zero (no delay) which  is
only suitable where a hardware CTS is available. Otherwise, a value between 2
and 6 is suitable for most rigs. (Note that when the delay is not 0, there is
uncertainty  of up to one tick, which  is the time  between when the transmit
order was received and the next timer tick,  so  use  the next higher value.)
The  CTS delay  may  also be set as one of  the parameters when the driver is
installed, in which case it will override the default value of zero.


HAPN1.SYS Device Driver                                                     4


Reset the 8273


Load ah with 12, and load al with the  port number.  Call  the  api. The 8273
will be reset.



Get HAPN-1.SYS size


Load  ah with 13  and call the api. On  return,  ax will contain the size the
driver occupies in memory.



Get transmitter status


Load ah with  14, and load al  with the  port  number, and  call the api.  On
return, ax will contain 0 if the transmitter is idle and 1 if the transmitter
is busy.



Get number of ports for this driver


Load ah with 15  and call the api. On return  ax will contain the  number  of
ports available in this driver. Generally, the number of ports will be 1  but
may be 2 or more.



Get maximum frame size


Load ah with 16 and call the api. On return ax will contain the largest frame
that can be received or transmitted  by this  driver.  The size  includes the
ax.25 address field.



Get duplex mode


Load ah with 17 and  call the api. On return ax will contain  0 for HDX and 1
for FDX.



Query Rx Data Available


Load  ah with 18 and the physical port id in al, and call the api.  On return
ax will contain 0 if no Rx data is avilable, or  the length of the next frame
if available.




HAPN1.SYS Device Driver                                                     5


Set duplex mode


Load ah with 19 and cl with 0 (HDX) or 1 (FDX) and call the api.



Query reserve status


Load ah  with  20 and call the api. If reserve=y was specified on the command
line, 1 will be returned, otherwise 0 will be returned in ax.



Query if any Tx buffers available


Load ah with 21 and al with the physical port id, and call the api.  If there
is at least one Tx buffer free 1 is returned in ax, otherwise 0 is returned.



Get port name


Load ah with 22 and al with the physical port  id, and place the address of a
30-byte buffer in es:di.  On return,  the  name of the port is  moved  to the
buffer, as a null-terminated string.



TRACE TABLE DESCRIPTION


The trace  table consists of a four byte header and  a quantity of data.  The
header contains a 2-byte integer specifying  the  length of the  data,  and a
2-byte  integer  specifying the offset in the data area to the location where
the next byte will be entered. The data area wraps around from the  bottom to
the top, so the 2nd header integer points to where the oldest byte is. As new
data is written over old data in  the table, the  oldest  entry may be partly
overwritten, and will  therefore be  incomplete.  The table is initialized to
nulls and nulls are interpreted as unused areas.

Each trace table entry has the following format:

    One byte code (alphabetic) defining the entry type.

    Four byte time stamp. This is present in all entries  except Rx  data and
    Tx data. The time stamp is  a long integer and consists of the timer tick
    counter in the driver.  Therefore, the  resolution is only in units of 55
    ms. and cannot distinguish events between timer ticks.

    Zero or more bytes of data for the entry.


 Code   Additional Data                          Description Of Entry
======  =======================================  ===========================
B (42)  Rx-byte                                  8273 byte received


HAPN1.SYS Device Driver                                                     6


C (43)                                           8273 Rx command issued
D (44)  Tx-byte                                  8273 byte transmitted
E (45)  8273-stat-reg hapn1-stat-1 hapn1-stat-2  8273 Rx results malfunction
F (46)                                           Timer: Raise RTS
G (47)                                           HAPN-1 activate driver
H (48)                                           8273 Tx timeout error
K (4B)                                           HAPN-1 deactivate driver
M (4D)                                           Disable Rx before Tx
P (50)                                           8273 reset
Q (51)                                           Enable 8273 rcv after reset
R (52)                                           TxInt: Rx command issued
S (53)  8273-status-reg                          8273 unknown interrupt
T (54)                                           8273 Rx timeout error
X (58)  8273-ric rx-len-lsb rx-len-msb ctrl-byte 8273 Rx result
Y (59)  8273-tic                                 8273 Tx result














































HAPN1.SYS Device Driver                                                     7